.\" $Id: PAPI_destroy_eventset.3,v 1.11 2004/09/28 16:12:03 london Exp $
.TH PAPI_destroy_eventset 3 "September, 2004"  "PAPI Programmer's Reference" "PAPI"

.SH NAME
PAPI_destroy_eventset, PAPI_cleanup_eventset  \-  empty and destroy an EventSet

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int\ PAPI_cleanup_eventset(int " EventSet ");"
.BI "int\ PAPI_destroy_eventset(int *" EventSet ");"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_cleanup_eventset(C_INT\  EventSet,\  C_INT\  check )
.BI PAPIF_destroy_eventset(C_INT\  EventSet,\  C_INT\  check )
.fi

.SH DESCRIPTION
.B PAPI_cleanup_eventset()
removes all events from a PAPI event set and turns off profiling
and overflow for all events in the eventset. This can not be 
called if the EventSet is not stopped.

.B PAPI_destroy_eventset()
deallocates the memory associated with an empty PAPI event set.

.SH ARGUMENTS
.I "EventSet"
--  an integer handle for a PAPI event set as created by
.BR "PAPI_create_eventset" (3).

.I "*EventSet"
--  a pointer to the integer handle for a PAPI event set as created by 
.BR "PAPI_create_eventset" (3).
The value pointed to by EventSet is then set to PAPI_NULL on success.

.SH RETURN VALUES
 On success, this function returns
.B "PAPI_OK."
 On error, a non-zero error code is returned.
                                                                                
.SH ERRORS
.TP
.B "PAPI_EINVAL"
One or more of the arguments is invalid. Attempting to
destroy a non-empty event set or passing in a null pointer
to be destroyed.
.TP
.B "PAPI_ENOEVST"
The EventSet specified does not exist.
.TP
.B "PAPI_EISRUN"
The EventSet is currently counting events.
.TP
.B "PAPI_EBUG"
Internal error, send mail to ptools-perfapi@ptools.org and complain.

.SH EXAMPLES
.nf
.if t .ft CW
/* Remove all events in the eventset */

if (PAPI_cleanup_eventset(EventSet) != PAPI_OK)
  handle_error(1);

/* Free all memory and data structures, EventSet must be empty. */

if (PAPI_destroy_eventset(&EventSet) != PAPI_OK)
  handle_error(1);
.if t .ft P
.fi

.SH BUGS
If the user has set profile on an event with the
.BR "PAPI_profil "(3) 
call, then when destroying
the EventSet the memory allocated by 
.BR "PAPI_profil "(3) 
will not be freed. The user should turn off 
profiling on the Events before destroying the 
EventSet to prevent this behavior.

.SH SEE ALSO
.BR PAPI_create_eventset "(3), "PAPI_add_event "(3), " PAPI_stop "(3), " 
.BR PAPI_profil "(3) "
